Skip to content

Made each chapter more readable as a stand-alone tutorial - #1520

Open
samuelafolabi wants to merge 10 commits into
wadpac:mainfrom
samuelafolabi:main
Open

Made each chapter more readable as a stand-alone tutorial #1520
samuelafolabi wants to merge 10 commits into
wadpac:mainfrom
samuelafolabi:main

Conversation

@samuelafolabi

@samuelafolabi samuelafolabi commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Fixes #1517

  • Existing tests still work (check by running the test suite, e.g. from RStudio).
  • Documentation updated:
    • Chapter vignettes for GitHub IO
  • Corresponding issue tagged in PR message. If no issue exist, please create an issue and tag it.
  • Updated release notes in inst/NEWS.Rd with a user-readable summary. Please, include references to relevant issues or PR discussions.

@samuelafolabi samuelafolabi changed the title Made each chapter more readable as a stand-alone tutorial (#1517) Made each chapter more readable as a stand-alone tutorial Jun 24, 2026
vincentvanhees
vincentvanhees requested changes Jul 4, 2026
View reviewed changes

@vincentvanhees vincentvanhees left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work @samuelafolabi
I spotted a few minor issues after building the pages locally:

  1. In chapter 8 the header of the minimal example lacks an empty line:
Image

  1. Why is the "On this page" table of contents sometimes displayed at the bottom (chapter 1, 2, 3, and 7) and sometimes on the right (all other chapters)? I think on the top right is most intuitive because a visitor typically arrives at the top and may want to jump to a section from there?

  2. Videos have 153 error, which may be related to my browser settings, but it may be a general problem:

Image

AI tells me "When embedding a YouTube video via an <iframe>, you may need to adjust how your website handles security and tracking headers. Add referrerpolicy="strict-origin-when-cross-origin" directly inside your YouTube <iframe> tag." What do you think?

  1. I like that you reference to Stuart's videos to acknowledge community contributions. I have not been involved in making these videos and I remember that there were some things in it that I would not recommend myself. Also, I do not know whether the videos are still relevant for learning the current version of GGIR. Did you watch them and find them useful for learning GGIR? If yes, then let's keep them. Further, I am wondering whether there should be a warning that content of videos may not be up to date with latest version of GGIR? or is that something the viewer should judge for themselves?

  2. When I build the pages locally I see a few warnings (below), are they easy to address?

── Building articles ───────────────────────────────────────────────────────────
Writing articles/index.html
Reading vignettes/chapter0_Contributing.Rmd
Writing articles/chapter0_Contributing.html
Reading vignettes/chapter0_GetStarted.Rmd
Writing articles/chapter0_GetStarted.html
WARNING] Div at file34c47f2573e4.md_chunk line 4 column 1 unclosed at file34c47f2573e4.md_chunk line 6 column 1, closing implicitly.
Reading vignettes/chapter0_Installation.Rmd
Writing articles/chapter0_Installation.html
Reading vignettes/chapter0_Support.Rmd
Writing articles/chapter0_Support.html
Reading vignettes/chapter1_WhatIsGGIR.Rmd
Writing articles/chapter1_WhatIsGGIR.html
WARNING] Div at file34c45ec42633.md_chunk line 4 column 1 unclosed at file34c45ec42633.md_chunk line 6 column 1, closing implicitly.
Reading vignettes/chapter10_SleepAnalysis.Rmd
Writing articles/chapter10_SleepAnalysis.html
Reading vignettes/chapter11_DescribingDataCutPoints.Rmd
Writing articles/chapter11_DescribingDataCutPoints.html
Reading vignettes/chapter12_TimeUseAnalysis.Rmd
Writing articles/chapter12_TimeUseAnalysis.html
WARNING] Div at file34c477284eda.md_chunk line 4 column 1 unclosed at file34c477284eda.md_chunk line 6 column 1, closing implicitly.
Reading vignettes/chapter13_CircadianRhythm.Rmd
Writing articles/chapter13_CircadianRhythm.html
Reading vignettes/chapter14_BehaviouralFragmentation.Rmd
Writing articles/chapter14_BehaviouralFragmentation.html
Reading vignettes/chapter2_Pipeline.Rmd
Writing articles/chapter2_Pipeline.html
WARNING] Div at file34c449042314.md_chunk line 4 column 1 unclosed at file34c449042314.md_chunk line 6 column 1, closing implicitly.
Reading vignettes/chapter3_QualityAssessment.Rmd
Writing articles/chapter3_QualityAssessment.html
WARNING] Div at file34c4b0d6303.md_chunk line 4 column 1 unclosed at file34c4b0d6303.md_chunk line 6 column 1, closing implicitly.
Reading vignettes/chapter4_AccMetrics.Rmd
Writing articles/chapter4_AccMetrics.html
```

@samuelafolabi

samuelafolabi commented Jul 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

@vincentvanhees Apologies for the late response.

  1. Just fixed the minimal example header.

  2. Since I can't run pkgdown::build_site(), I built each page (in isolation) locally by knitting each of the chapters directly on RStudio, so I could not view the "On this Page" section of the page locally.
    The problem seems to be a responsive breakpoint issue that even exists on the current live version. For reference, this happens in Chapter 4 (https://wadpac.github.io/GGIR/articles/chapter4_AccMetrics.html) when you reduce the browser window size, but stays on the right hand side when the screen is large enough.

image I'll find a way to fix that soon, and I'll feed you back.
  1. I had the same 153 error when I open the page in my browsers, but it works well on the RStudio knit viewer. (Error 153) is a YouTube security restriction indicating it couldn't decipher the "Referrer" policy of the page hosting it. It is how most browsers handle "file:///" security for third-party embeds. It should work without issue when hosted online via github.io page since that serves from a real "https://" domain.
image

  1. I find them quite useful. I think I'll add a disclaimer or/and label it as part of community efforts by users to show new users their way around the package. I'll also add the version used in the video too.

  2. Fixed all local builds warnings. Please let know if you encounter any other local build warnings.

@vincentvanhees

vincentvanhees commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Thanks, I will look at this later in the week.
In relation to "Since I can't run pkgdown::build_site()". Sorry, that may not have been clear from the documentation. What I meant is that you should not commit the result of this command. So, you can run it locally to test the updates but just make sure the file changes that pkgdown makes are not included in a commit.

@vincentvanhees

vincentvanhees commented Aug 6, 2026

Copy link
Copy Markdown
Member

I have been thinking about the videos and would like to exclude them for the following reasons.

  • The instructions are partially outdated, e.g. I want researchers to stop using g.shell.GGIR() such that we can deprecate that function some day. It does not help if videos keep promoting the function. Similarly there are parameters being referenced in the videos that were deprecated, which I think is confusing for new users, because they think that they are controlling something inside GGIR that they are actually not controlling.
  • The instructions are sometimes incorrect, e.g. GGIR users should not use library() for all GGIR dependencies, because then you get issues like Error in verisense_count_steps with default parameters — 'length = 5' in coercion to 'logical(1)' #1529
  • Most of the GGIR documentation is text-only to ease maintenance. I understand that including videos or visualizations is nice if they are good and well designed, but this only works if there are people willing to maintain the videos and visualisation to keep them aligned with the text. Without such effort I think it is better to keep the documentation minimalistic such that it is easy to update if and when GGIR code is updated.
  • We already acknowledge Stuart's videos in https://wadpac.github.io/GGIR/articles/chapter0_Contributing.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vincentvanhees vincentvanhees vincentvanhees requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Make each documentation chapter more readable as a stand-alone tutorial

2 participants

@samuelafolabi @vincentvanhees